ngAnimate ( directive in module ng )

Description

The ngAnimate directive works as an attribute that is attached alongside pre-existing directives. It effects how the directive will perform DOM manipulation. This allows for complex animations to take place without burdening the directive which uses the animation with animation details. The built in directives ngRepeat , ngInclude , ngSwitch , ngShow , ngHide and ngView already accept ngAnimate directive. Custom directives can take advantage of animation through $animator service.

Below is a more detailed breakdown of the supported callback events provided by pre-exisitng ng directives:

Directive Supported Animations

ngRepeat

enter, leave and move

ngView

enter and leave

ngInclude

enter and leave

ngSwitch

enter and leave

ngShow & ngHide

show and hide

You can find out more information about animations upon visiting each directive page.

Below is an example of a directive that makes use of the ngAnimate attribute:

<!-- you can also use data-ng-animate, ng:animate or x-ng-animate as well -->
<ANY ng-directive ng-animate="{event1: 'animation-name', event2: 'animation-name-2'}"></ANY>

<!-- you can also use a short hand -->
<ANY ng-directive ng-animate=" 'animation' "></ANY>
<!-- which expands to -->
<ANY ng-directive ng-animate="{ enter: 'animation-enter', leave: 'animation-leave', ...}"></ANY>

<!-- keep in mind that ng-animate can take expressions -->
<ANY ng-directive ng-animate=" computeCurrentAnimation() "></ANY>

The event1 and event2 attributes refer to the animation events specific to the directive that has been assigned.

Keep in mind that if an animation is running, no child element of such animation can also be animated.

CSS-defined Animations

By default, ngAnimate attaches two CSS3 classes per animation event to the DOM element to achieve the animation. It is up to you, the developer, to ensure that the animations take place using cross-browser CSS3 transitions. All that is required is the following CSS code:

<style type="text/css">
/*
 The animate-enter prefix is the event name that you
 have provided within the ngAnimate attribute.
*/
.animate-enter-setup {
 -webkit-transition: 1s linear all; /* Safari/Chrome */
 -moz-transition: 1s linear all; /* Firefox */
 -ms-transition: 1s linear all; /* IE10 */
 -o-transition: 1s linear all; /* Opera */
 transition: 1s linear all; /* Future Browsers */

 /* The animation preparation code */
 opacity: 0;
}

/*
 Keep in mind that you want to combine both CSS
 classes together to avoid any CSS-specificity
 conflicts
*/
.animate-enter-setup.animate-enter-start {
 /* The animation code itself */
 opacity: 1;
}
</style>

<div ng-directive ng-animate="{enter: 'animate-enter'}">
</div>

Upon DOM mutation, the setup class is added first, then the browser is allowed to reflow the content and then, the start class is added to trigger the animation. The ngAnimate directive will automatically extract the duration of the animation to determine when the animation ends. Once the animation is over then both CSS classes will be removed from the DOM. If a browser does not support CSS transitions then the animation will start and end immediately resulting in a DOM element that is at it's final state. This final state is when the DOM element has no CSS animation classes surrounding it.

JavaScript-defined Animations

In the event that you do not want to use CSS3 animations or if you wish to offer animations to browsers that do not yet support them, then you can make use of JavaScript animations defined inside ngModule.

var ngModule = angular.module('YourApp', []);
ngModule.animation('animate-enter', function() {
  return {
    setup : function(element) {
      //prepare the element for animation
      element.css({ 'opacity': 0 });
      var memo = "..."; //this value is passed to the start function
      return memo;
    },
    start : function(element, done, memo) {
      //start the animation
      element.animate({
        'opacity' : 1
      }, function() {
        //call when the animation is complete
        done()
      });
    }
  }
});

As you can see, the JavaScript code follows a similar template to the CSS3 animations. Once defined, the animation can be used in the same way with the ngAnimate attribute. Keep in mind that, when using JavaScript-enabled animations, ngAnimate will also add in the same CSS classes that CSS-enabled animations do (even if you're using JavaScript animations) to animated the element, but it will not attempt to find any CSS3 transition duration value. It will instead close off the animation once the provided done function is executed. So it's important that you make sure your animations remember to fire off the done function once the animations are complete.

Usage

as attribute
<ANY ng-animate="{expression}">
   ...
</ANY>
as class
<ANY class="ng-animate: {expression};">
   ...
</ANY>

Parameters